#!/usr/bin/env python

"""
glittr - a Python interface to the Flickr API

Overview
========

The Flickr class is a low-level interface to the Flickr API that returns normal
python objects.  The Glittr class is a higher-level interface that has its own
classes for different types of objects found on Flickr, e.g. User, Photo, and
Photoset.  These objects have methods that call Flickr API methods in an
easy-to-use fashion.

The idea is that the Flickr class contains almost no information about the
Flickr API, it will try to call almost any method you tell it to, only the
special ones like 'upload' and 'replace' have to built-in.

Meanwhile, the Glittr class has to know all about these methods, its job is to
take the random assortment of available API calls and make a sort of coherent
whole.  So while different Flickr API methods may or may not, for instance,
return different pages or have setMeta instead of editMeta, Glittr methods are
fairly consistent, they automatically grab any pages, if there are any, convert
objects to Glittr classes, like the Photo class, and let you access and set
attributes, such as photo.title.


Flickr Usage
============

How to use Flickr:

    from glittr import *
    flickr = Flickr(config='flickr.ini')
    # optional, allows you to modify things and access private information
    flickr.login()
    print flickr.people.getInfo(user_id='79661467@N00')

All Flickr API methods should be accessible in this manner, they all return
python objects (like dictionaries).  That's pretty much it, all the
documentation for the available methods is available online at
http://www.flickr.com/services/api/.

The Flickr class has built-in help, of a sort.  If you're lazy and don't want
to go to the Flickr API webpage, but have a working api key in your ini file,
you might try:

    flickr = Flickr(config='flickr.ini')
    help(flickr.people.getInfo.help)

The extra .help appears to be necessary for this to work.  There's also
tab-completion of Flickr methods!


Glittr Usage
============

How to use Glittr:

    g = Glittr(flickr) # the flickr object you've already created

    chris = g.find_user('cshesse')
    for photo in chris.photos:
        print photo.title

There are two ways to access the various methods of Glittr objects that return
information: as methods that return generators (or other python objects), such
as .get_photos() on a User object:
    
    for photo in chris.get_photos(): print photo

And as an attribute that returns a list (wherever the .get_*() method would
return a generator) and caches the response:

    for photo in chris.photos:
        print photo

The method call will ask Flickr each time for the response.  You can make the
attributes do this as well by telling the Glittr object to turn off caching
when you create it:

    g = Glittr(flickr, caching=False)

The method form lets you give the function keyword arguments:

    for photo in chris.get_photos(text='squirrel'):

The keyword arguments that the method accepts are the same as the Flickr API
method that it wraps.  Use help() on it to see what method is being called, and
look at http://www.flickr.com/services/api/ to see what parameters you can give
the function.

The attributes are handy because, when possible, they let you just use normal
assignment to give values to things, instead of using the .set_*() methods:

    for photo in chris.photos:
        photo.title = 'Totally Awesome Photo'

For more information about a class or method, try using the help() function on
it.


Subclassing
===========

If you want to subclass Glittr objects so that your subclasses are returned
instead of the default ones, here's one way to do it:

    import glittr
    class MyUser(glittr.User):
        def my_method(self):
            print "i'm useful!"
    glittr.User = MyUser

Now when you call, for instance, .find_user(), it will return instances of your
class:

    >> me = g.find_user('cshesse')
    >> print me
    <Flickr MyUser: id='79661467@N00' 'cshesse'>


Limitations
===========

    There is a global Flickr instance used by Glittr, so you can't have
    multiple Glittr objects that use different Flickr objects (for instance,
    each Flickr object could be logged in as a different person).  If anyone
    wants this, let me know.


Thanks
======

Thanks to Brian Beck <exogen@gmail.com> for some coding advice!


License (BSD)
=============

Copyright (c) 2007 Christopher Hesse <csh@scourcritical.com>
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

    * Redistributions of source code must retain the above copyright notice,
      this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright notice,
      this list of conditions and the following disclaimer in the documentation
      and/or other materials provided with the distribution.
    * Neither the name of CHI nor the names of its contributors may be used to
      endorse or promote products derived from this software without specific
      prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
"""

__version__ = "20070325"

import logging 

# module imports
from flickr import Flickr
from error import *
from classes import *
from glittr import Glittr
from authcache import AuthCache
from config import LOGGER_NAME

# Set up module-level logger. (thanks, flup!)
console = logging.StreamHandler()
console.setLevel(logging.DEBUG)
console.setFormatter(logging.Formatter('%(asctime)s : %(message)s',
                                       '%Y-%m-%d %H:%M:%S'))
logging.getLogger(LOGGER_NAME).addHandler(console)
del console

if __name__ == "__main__":
    api_key = raw_input("what is your api key? ")
    shared_secret = raw_input("what is your shared secret? ")
    flickr = Flickr(api_key=api_key, shared_secret=shared_secret)
    print flickr.people.getInfo(user_id='79661467@N00')
